Skip to content

Generate tmux capability pages from port registries - #151

Draft
tony wants to merge 8 commits into
bump-min-tmux-000from
bump-min-tmux-001
Draft

tony wants to merge 8 commits into
bump-min-tmux-000from
bump-min-tmux-001

Conversation

@tony

@tony tony commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Generate the tmux capability pages from each port's own capability registry, instead of a table kept by hand in the tmux support guide. This is stacked on the core minimum change.

Each port's features change adds a typed support.capabilities registry. The library refuses with that same registry, and the port emits it as capabilities.json (schema libtmux-capabilities/1), with a drift test in its own CI. This PR reads those manifests the same way the site reads each port's API:

  • packages/api-model/src/capabilities.ts defines the schema. It validates a manifest and reports every problem at once, orders versions the way tmux prints them (next-X.Y < X.Y-rc < X.Y-rcN < X.Y < X.Ya), and computes each cell from the entry's since, except and handling. No cell is stored.
  • scripts/gen-capabilities.mjs reads each port checkout's manifest and resolves every API and error name through that port's API model. It fails on a name the model lacks, so a renamed method cannot leave a capability pointing at nothing. The release columns come from tmux's own refs: final tags, release branches (3.7d shipped from one), and the next-X.Y that master names.
  • reference/capabilities/ is the page:
    • In a port build, a capability × tmux release matrix from the port's floor, then release workarounds. Every API, refusal type and tmux command links to its reference page.
    • In the root build, a capability × port map naming the release each port needs.
  • Each tmux command reference page gets a "Support in libtmux" table, MDN style: the ports that gate the command and the release each needs.
  • The matrix uses a fixed layout: equal-width columns, a sticky capability column, an icon and a screen-reader label in every cell, and a legend of the states used.
  • The tmux support guide keeps its explanation and links to the generated map. The feature, state and per-port tables are gone, and a test keeps release tables out of the guide.

Only ports that publish a manifest appear; nothing stands in for the rest. Lua is the first, on libtmux-lua#36. Run against that branch's manifest, the generator resolves all of its API names over 14 releases, 3.3a through next-3.9. The committed data stays empty until a port's registry lands on its trunk, because the site reads each port at the revision it builds.

Validation:

  • packages/api-model: the capability tests cover version order, every cell state and each validation failure. Ignoring except fails the cell test.
  • site: the generator test links a fixture manifest's names, and fails with the missing name when a fixture names a method the model lacks. The matrix test checks equal column widths, a labelled cell per column and the legend; uneven widths fail it. The guide test rejects a release table and requires the link to the map. The glossary navigation suite still passes with the command-support section in ApiReference.
  • test-all.sh runs gen-capabilities.mjs --check.

Not yet: the assembled-site build and the publication audit run in hosted CI. The other ports' registries come with their features changes.

Closes #147.

tony added 2 commits October 17, 2026 04:35
why: A shared 3.3a floor does not make every control, buffer, shell or
layout operation safe on that release. Readers had no page that says
which features need a newer tmux, what a library does below it, and
which ports have evidence for their refusal.

what:
- Add the optional features to the tmux support guide: library-managed
  control mode from 3.7, named buffer deletion and rename from 3.4,
  captured run-shell output outside 3.3 and 3.4, exact 3.7 break-pane
  and name restrictions, split percentages sent as -l N%, and layout
  validation below 3.4
- Define the five support states (Non-operative, Timing-sensitive,
  Operative with synchronization, Qualified, Unverified) and give the
  native state for each affected release
- Name what the Python, tmuxp, Go and Rust changes enforce, and mark
  every other port Unverified until its change has checked evidence
- State that guards cover library-chosen operations and literal command
  items, not opaque shell text or configured alias bodies
- Update the guides index card to mention optional features
why: The optional-feature page is only useful while each feature keeps
its own requirement, the states use the contract's names and results
name ports instead of summarizing them as a ratio.

what:
- Require a table row for each optional feature with its tmux release
- Require a defining row for each of the five support states
- Reject ratios such as "5/8" or "five of eight" and require every port
  group in the port table

Verified: the check passes; dropping the Unverified row, changing the
named-buffer requirement to 3.3 and replacing a port group with a
"five of eight" count each make it fail on the matching case, and the
restored page passes.
@tony
tony force-pushed the bump-min-tmux-000 branch from 2a58002 to 99df2a3 Compare October 17, 2026 13:38
@tony
tony force-pushed the bump-min-tmux-001 branch 2 times, most recently from 24dd014 to ad179f0 Compare October 17, 2026 16:34
@tony
tony force-pushed the bump-min-tmux-000 branch from 564121d to 7a7a677 Compare October 17, 2026 17:54
@tony
tony force-pushed the bump-min-tmux-001 branch from ad179f0 to 3d7407a Compare October 17, 2026 17:54
@tony
tony force-pushed the bump-min-tmux-000 branch from 7a7a677 to 4d5d622 Compare October 17, 2026 18:53
@tony
tony force-pushed the bump-min-tmux-001 branch from 3d7407a to 7c2740a Compare October 17, 2026 18:53
tony added 6 commits October 17, 2026 15:32
why: Each port's typed capability registry is the only source for the
capability pages, so the site needs one shape to read and a way to say
exactly what a port's emitted manifest gets wrong.

what:
- Define libtmux-capabilities/1: floor, capabilities with since,
  except, handling, error, API names and tmux commands, and release
  workarounds
- Order versions as tmux prints them: next-X.Y < X.Y-rc < X.Y-rcN <
  X.Y < X.Ya, refusing forms tmux never prints
- Compute each cell from the entry instead of storing it
- Report every problem in a manifest at once, with tests for each
why: A table typed into a guide drifts from the code it describes. The
capability pages must come from what each port's registry says, with
every API name tied to that port's reference.

what:
- Read capabilities.json from each port checkout, validate it, and
  resolve each API and error name through the port's API model
- Fail on a name the model lacks instead of rendering plain text
- Take release columns from tmux's own refs: final tags, release
  branches (3.7d), and the next-X.Y master names
- Run the check in test-all, with a fixture manifest that names a
  missing method to show the gate fails
why: Prose cells of different lengths made the old table jagged and hard
to scan. A map reads down a release and across a capability.

what:
- Lay the table out fixed, with equal-width data columns and a sticky
  capability column
- Show an icon per cell with a screen-reader label, and a legend of
  only the states the table uses
- Test equal widths, one labelled cell per column, and the legend;
  uneven column widths fail the first test
why: Readers need to know what a port does on their tmux release and
which methods that affects, from the port's own registry.

what:
- Add reference/capabilities: per port in a port build, a capability
  by tmux release matrix from the port's floor, plus workarounds
- In the root build, a capability by port map naming the release each
  port needs
- List each capability's API, refusal type and tmux commands as links
  to the reference
- Show only ports that publish a manifest, never a stand-in row
why: A reader on a tmux command's reference page should see which
libtmux ports gate that command and on which releases, the way MDN
shows browser support on an API page.

what:
- Render a ports matrix of every capability and workaround that names
  the command, linking each row to the capability map
- Add it to the page contents when a port gates the command
- Bind the capability helper in the glossary navigation test
why: The guide kept three hand-written tables of feature releases,
support states and per-port claims. They had already fallen behind the
ports and could not link to the methods involved.

what:
- Keep the explanation of optional features and what guards cover
- Drop the feature, state and per-port tables
- Link to the generated capability map
- Test that the guide holds no table of release requirements
@tony tony changed the title Record optional tmux feature requirements Generate tmux capability pages from port registries Oct 17, 2026
@tony
tony force-pushed the bump-min-tmux-001 branch from 71566f4 to 2a87df5 Compare October 17, 2026 20:40

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant